home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-04 / win-fort.zip / F4W3API.DOC < prev    next >
Text File  |  1992-01-06  |  14KB  |  311 lines
  1. Fortran For the Windows 3.0 API
  2. Version 1.00. 04-Jan-1992.
  3. By Kevin B Black (L_KBB@UK.AC.NWL.VB).
  4.  
  5. Introduction
  6. ============
  7.  
  8. This is a brief startup guide to Windows 3.0 programming using Microsoft
  9. Fortran version 5.1. You may have found that the `QuickWin' interface is a bit
  10. of a disappointment, if you were hoping to develop true Windows 3.0 application
  11. in Fortran. Next, you read in the Advanced Topics manual, page 139, under
  12. Windows Programming that you can not call the Windows 3.0 applications
  13. interface directly Fortran (Buying Microsoft C and the SDK could prove
  14. expensive). Well this does not seem to be true, and this guide (with the
  15. accompanying files) shows you how to do it.
  16.  
  17. While reading through these notes, you can think about using the FORTWIN and
  18. FWCLOCK sources as examples when building your own applications.
  19.  
  20. Other things you will need
  21. ==========================
  22.  
  23. Apart from the Microsoft Fortran version 5.1 compiler, you will also need some
  24. manuals describing the Windows 3.0 application interface. The manuals supplied
  25. with Microsoft's Software Development Kit (SDK) are excellent as reference
  26. manuals, and I believe can be purchased separately from the SDK.
  27.  
  28. You will probably need some `tools', for example an Icon editor. A Dialogue
  29. editor is also useful for writing the more complicated applications; although
  30. creating text based dialogue files can give you more `precision' than a
  31. Dialogue Editor over the placement of Buttons and text etc. Such tools are
  32. provided with the SDK, but are also available as Shareware or in the Public
  33. Domain.
  34.  
  35. Libraries
  36. =========
  37.  
  38. If you have not created Windows libraries for use with Microsoft Fortran, then
  39. you should do this now. Run the SETUP program again, choose the `Load or build
  40. additional libraries' option and build libraries for `DOS and Windows'. You
  41. don't need to create C compatible libraries; unless you are planning on mixed
  42. language programming. After building the libraries you should find two new
  43. libraries :
  44.  
  45.       NOQWIN.LIB and LLIBFEW.LIB.
  46.  
  47. There may be more additional libraries, depending on the options you chose
  48. during SETUP. I strongly recommend appending the letter C to Fortran libraries
  49. built for C compatibility. For example :
  50.  
  51.    Fortran      C Compatible
  52.     Libraries    Libraries
  53.  
  54.    LLIBFEW.LIB   LLIBFEWC.LIB
  55.    LLIBFORE.LIB  LLIBFEC.LIB
  56.  
  57. Compiling
  58. =========
  59.  
  60. To compile a program that you for use with Windows 3.0, the /Gw switch is
  61. required, the /MW switch should not be used. An example compilation command is :
  62.  
  63.    FL /c /AH /Zp /FPi /Gw WNDPROC.FOR
  64.  
  65. Bear in mind that there is no `main' program in a Windows 3.0 application, so
  66. any code you placed in a main program is not going to get executed. Instead a
  67. Windows 3.0 application has a subroutine called `WinMain', which is called by
  68. the Windows 3.0 startup code for the application (this is found in the
  69. LLIBFEW.LIB library, and is included automatically when you link your program).
  70.  
  71. If you have not installed the Windows SDK kit, then you will need to add the
  72. path d:\WINDEV\INCLUDE to your INCLUDE path (or include the path explicitly in
  73. your source programs). This is so the compiler can find the WINDOWS.FI and
  74. WINDOWS.FD files, which will have been copied to that directory.
  75.  
  76. If you do not use IMPLICIT NONE in your program sources, then the /4Yd compiler
  77. switch is recommended, to force you to declare your variables.
  78.  
  79. The more free DOS memory available when you are compiling the better, DOS 5.0
  80. is useful here. Using the `make' utility reduces the heap space available to
  81. the compiler. This can result in an F1002; Out of heap space compiler error
  82. during compilation.
  83.  
  84. Linking
  85. =======
  86.  
  87. Once you have compiled your program, and built any necessary resources, then
  88. you can link it. To do this you need to do several thing. Firstly, you need to
  89. create a .DEF file, use the FL.DEF (supplied with the Fortran Compiler) or
  90. FWCLOCK.DEF (supplied with this file) files as templates. Next you will need to
  91. extract the NOQWIN module from the NOQWIN library, for example :
  92.  
  93.    LIB d:\path_to_fortran_libs\NOQWIN.LIB *noqwin;
  94.  
  95. You may need to do this before you can build the examples if they are not
  96. located on the same disk as your compiler, or you installed the compiler in a
  97. non standard directory. Alternatively you can edit their `make files'. You
  98. can, of course, place this command in the make or BAT file that you use to
  99. build your application.
  100.  
  101. When linking your application, you need to specify the NOQWIN module to
  102. prevent the QuickWin environment from being loaded, and also the .DEF file to
  103. create a proper Windows executable. A simple link command would be as follows :
  104.  
  105.    LINK SMALLPRG NOQWIN ,,, /NOD LLIBFEW, SMALLPRG.DEF;
  106.  
  107. For any non-trivial application a linker `response' file is recommended.
  108.  
  109. Important Things to be aware of
  110. ===============================
  111.  
  112. You need to DEFINE meta-command symbols to include the various Windows
  113. interface statements and parameters, contained in the WINDOWS.FI and WINDOWS.FD
  114. file, that you may use in a routine. The reason for this is that if all entries
  115. are enabled, then the compiler will usually run out of heap space while trying
  116. to compile your program. Thus it is important to remember to enable those
  117. functions you wish to use, and that you may not always get a compiler error if
  118. you forget (and the result is your application will not perform properly). This
  119. can still be a problem, especially when compiling using the `make' utility. It
  120. does tend to be caused by the Fortran interface and parameter declarations in
  121. the WINDOWS.FI and WINDOWS.FD files. Hopefully a future version of the compiler
  122. will remove this restriction. Failure to enable function declarations should
  123. show up if you use the IMPLICIT NONE statement, or compile your programs with
  124. the /4Yd switch.  The following table shows which symbols need to be defined to
  125. enable specific types of Windows function or parameter specifications :
  126.  
  127.    GDICAPMASKS      - CC_*, LC_*, PC_*, CP_*, TC_* and RC_
  128.    VIRTUALKEYCODES  - VK_*
  129.    WINMESSAGES      - WM_*, EM_*, LB_* and CB_*
  130.    WINSTYLES        - WS_*, CS_*, ES_*, LBS_*, SBS_* and CBS_*
  131.    SYSMETRICS       - SM_*
  132.    MENUS            - MF_*
  133.    ICONS            - IDI_*
  134.    KEYSTATES        - MK_*
  135.    SYSCOMMANDS      - SC_*
  136.    RASTEROPS        - Binary and Tertiary raster ops
  137.    SHOWWINDOW       - SW_*
  138.    OEMRESOURCE      - OEM Resource values
  139.    ATOM             - Atom Manager routines
  140.    CLIPBOARD        - Clipboard routines
  141.    COLOR            - Screen colours
  142.    CTLMGR           - Control and Dialogue routines
  143.    DRAWTEXT         - DrawText() and DT_*
  144.    GDI              - All GDI defines and routines
  145.    KERNEL           - All KERNEL defines and routines
  146.    USER             - All USER defines and routines
  147.    MB               - MB_* and MessageBox()
  148.    MEMMGR           - GMEM_*, LMEM_*, GHND, LHND, associated routines
  149.    METAFILE         - typedef METAFILEPICT
  150.    MSG              - typedef MSG and associated routines
  151.    OPENFILE         - OpenFile(), OemToAnsi, AnsiToOem and OF_*
  152.    SCROLL           - SB_* and scrolling routines
  153.    SOUND            - Sound driver routines
  154.    TEXTMETRIC       - typedef TEXTMETRIC and associated routines
  155.    WH               - SetWindowsHook and WH_*
  156.    WINOFFSETS       - GWL_*, GCL_* and associated routines
  157.    COMM             - COMM driver routines
  158.    KANJI            - Kanji support stuff.
  159.    HELP             - Help engine interface.
  160.    PROFILER         - Profiler interface.
  161.    DEFERWINDOWPOS   - DeferWindowPos routines
  162.  
  163. ---
  164.  
  165. One problem encountered during the initial stages of the investigation of
  166. Windows 3.0 API usage from Fortran was how to deal with the Windows internal
  167. resource descriptors and the passing of an address or NULL pointer to a Windows
  168. API function that can also take a user string. A number of ways to overcome
  169. this are possible, but the one chosen seems to be the most satisfactory way of
  170. doing it. This is to define two interfaces to the API function. The standard
  171. version takes a null terminated string. The second (which has _A appended to
  172. the function name) allows the programmer to specify the address, or an internal
  173. resource. Thus to load a user defined cursor, the LoadCursor function can be
  174. invoked as follows :
  175.  
  176.     hCursor=LoadCursor(NULL,'MyCursor'C)
  177.  
  178. or, if you wanted,
  179.  
  180.     hCursor=LoasCursor_A(NULL,LOCFR('MyCursor'C))
  181.  
  182. This allows an internal cursor to be load as follows :
  183.  
  184.     hCursor=LoadCursor_A(NULL,IDC_ARROW)
  185.  
  186. The following functions and subroutines currently have an _A form for some of
  187. their arguments :
  188.  
  189.    SetDIBits         GetDIBits         InvalidateRect
  190.    ValidateRect      ScrollWindow      ScrollDC
  191.    SetProp           GetProp           LoadCursor
  192.  
  193. ---
  194.  
  195. Not all the interfaces currently contained in WINDOWS.FI have been fully
  196. tested, so if you are having difficulty with some function compare its
  197. description to one that you know works. Some functions may be missing. But
  198. examination of the interface statements in WINDOWS.FI and the declarations in
  199. WINDOWS.FD will show you how to write versions for any missing function.
  200.  
  201. ---
  202.  
  203. The names of two parameters clashed with function names (C is case sensitive
  204. and Fortran is not). These were ExtTextOut and StretchBlt. The parameters were
  205. renamed as EXT_TEXTOUT and STRETCH_BLT.
  206.  
  207. ---
  208.  
  209. The two include files WINDOWS.FI and WINDOWS.FD do not look very neat, they
  210. have been designed for compactness and speed (during compilation).
  211.  
  212. ---
  213.  
  214. There are two ways in which FARPROC parameters to the Windows 3.0 API
  215. functions are passed, sometime they are Fortran EXTERNAL functions, and some
  216. times they are the address. For an example, compare the interface statements
  217. for the MakeProcInstance and FreeProcInstance functions.
  218.  
  219. ---
  220.  
  221. You can only run a Fortran application once from the same Windows .EXE
  222. executable, you can copy the .EXE file to another name and run it again. The
  223. reason for this strange behaviour of Windows is not known. You would have
  224. though that it could make its own entirely separate process copy of the
  225. program, rather than telling you can not run the application more than once.
  226.  
  227. ---
  228.  
  229. Sometimes the Fortran errors F3606 and F3607 may occur during compilation
  230. depending on the usage made of certain Windows functions. These two errors are
  231. non-fatal, and may not indicate a problem (although this will depend, of
  232. course, on the code). The Fortran warning F4202 may also occur during
  233. compilation. For an example of the above, compile the ABOUT module of the
  234. FWCLOCK application.
  235.  
  236. Sample Fortran applications
  237. ===========================
  238.  
  239. FORTWIN.EXE
  240.  
  241. FORTWIN.EXE is a Windows Generic application written entirely in Fortran, the
  242. source code to this is provided with the F4W3API1 kit.
  243.  
  244. FWCLOCK.EXE
  245.  
  246. FWCLOCK.EXE is a Windows Clock application written entirely in Fortran, the
  247. source code to this is provided with the F4W3API1 kit. The TimeZone feature
  248. has not been implemented; currently it demonstrates the grayed out menu item.
  249. The colours on the bit map, which is displayed in the `About Box', are not
  250. set; thus the picture (of me) may look a bit avant-garde.
  251.  
  252. File list
  253. =========
  254.  
  255. The following is a list of files provided in the F4W3API1 distribution kit :
  256.  
  257. Directory of \WINDEV\FORTRAN
  258.  
  259. F4W3API  DOC     13717  |  This file
  260. SUP      FOR      1244  |  Functions that cannot be written using `INTERFACE'
  261.  
  262. Directory of \WINDEV\FORTRAN\FORTWIN
  263.  
  264. FORTWIN           1202  |  Make file for FORTWIN generic application
  265. FORTWIN  CUR       326  |  Example cursor image
  266. FORTWIN  DEF       826  |  Linker definitions
  267. FORTWIN  EXE     29696  |  Windows 3.0 Executable
  268. FORTWIN  FD        153  |  Fortran include file, definitions
  269. FORTWIN  FI        828  |  Fortran include file, interfaces
  270. FORTWIN  FOR     12935  |  Fortran source file
  271. FORTWIN  H          57  |  Resource compiler header file
  272. FORTWIN  ICO       766  |  Icon images
  273. FORTWIN  RC        687  |  Resource compiler source file
  274. FORTWIN  RES      1517  |  Resources file
  275. X        BAT        15  |  Build all
  276.  
  277. Directory of C:\WINDEV\FORTRAN\FWCLOCK
  278.  
  279. ABOUT    FOR      2685  |  Fortran source for part of FWCLOCK
  280. DIGIT    FOR     10456  |  Fortran source
  281. DOWNTOOL FOR       497  |  Fortran source
  282. DRAWFACE FOR      4575  |  Fortran source
  283. DRAWHOUR FOR      2620  |  Fortran source
  284. DRAWHUB  FOR      1201  |  Fortran source
  285. DRAWMINU FOR      2430  |  Fortran source
  286. DRAWSECO FOR       635  |  Fortran source
  287. F        BAT        42  |  Compile procedure
  288. FWCLOCK           1453  |  Make file for FWCLOCK application
  289. FWCLOCK  BMP      4718  |  Bitmap
  290. FWCLOCK  DEF       317  |  Linker definitions file
  291. FWCLOCK  EXE     61952  |  Windows 3.0 Executable
  292. FWCLOCK  FD       4244  |  Fortran include file, definitions
  293. FWCLOCK  FI        460  |  Fortran include file, interfaces
  294. FWCLOCK  FOR      5257  |  Fortran source
  295. FWCLOCK  H         225  |  Resource compiler header file
  296. FWCLOCK  ICO      2038  |  Icon images
  297. FWCLOCK  LNK       151  |  Linker response file
  298. FWCLOCK  RC        972  |  Resource compiler source file
  299. FWCLOCK  RES      7261  |  Resources file
  300. INITFWC  FOR      1652  |  Fortran source
  301. RESIZE   FOR      1624  |  Fortran source
  302. TOOLUP   FOR       658  |  Fortran source
  303. WNDPROC  FOR     12991  |  Fortran source
  304. X        BAT        15  |  Build all
  305.  
  306. Directory of \WINDEV\INCLUDE
  307.  
  308. WINDOWS  FD     106831  |  Windows 3.0 API Fortran definitions, parameters
  309. WINDOWS  FI      70656  |  Windows 3.0 API Fortran interface statements
  310. --------------------------------------------------------------------------------
  311.